Walkthrough 3-1: Use API Designer to define an API with RAML

In this walkthrough, you create an API definition with RAML using API Designer. You will:

·       Define resources and nested resources.

·       Define get and post methods.

·       Specify query parameters.

·       Interact with an API using the API console.

  

Create a new Design Center project

1.     Return to Design Center.

2.     Click the Create button and select Create API specification.

3.     In the new specification dialog box, set the project name to American Flights API.

4.     Ensure Text editor is selected and click Create Specification; API Designer should open.

 

5.     Review the three sections of API Designer: the file browser, the editor, and the API console.

 

Add a RAML resource

6.     In the editor, place the cursor on a new line of code at the end of the file.

7.     Add a resource called flights.

View the API console

8.     Look at the API console on the right side of the window; you should see summary information for the API.

Note: If you do not see the API console, click the arrow located in the upper-right corner of the web browser window.

 

Add RAML methods

9.     In the editor, go to a new line of code and backspace so you are indented the same amount as the flights resource; look at the contents of the API Designer shelf.

Note: If you don’t see the API Designer shelf, it is either minimized or there is an error in your code. To check if it is minimized, go to the bottom of the web browser window and look for an arrow. If you see the arrow, click it to display the shelf.

10.  Indent by pressing the Tab key; the contents in the API Designer shelf should change.

 

11.  Click the get method in the shelf.

12.  Look at the API console; you should see a GET method for the flights resource.

13.  In the editor, backspace so you are indented the same amount as the get method.

14.  Click the post method in the shelf.

15.  Look at the API console; you should see GET and POST methods for the flights resource.

 

Add a nested RAML resource

16.  In the editor, backspace and then go to a new line.

17.  Make sure you are still under the flights resource (at the same indentation as the methods).

18.  Add a nested resource for a flight with a particular ID.

/{ID}:

19.  Add a get method to this resource.

20.  Look at the API console; you should see the nested resource with a GET method.

 

Add an optional query parameter

21.  In the editor, indent under the /flights get method (not the /flights/{ID} get method).

22.  In the shelf, click the queryParameters parameter.

23.  Add a key named destination.

  

24.  Indent under the destination query parameter and look at the possible parameters in the shelf.

25.  In the shelf, click the required parameter.

26.  In the shelf, click false.

27.  Go to a new line of code; you should be at the same indent level as required.

28.  In the shelf, click the enum parameter.

29.  Set enum to a set of values including SFO, LAX, and CLE.

  

Try to call an API method using the API console

30.  In the API console, click the GET method for the /flights resource.

31.  Review the information.

 

32.  Click the Try it button; you should get a message that the Request URL is invalid; a URL to call to try the API needs to be added to the RAML definition.

 



Did you complete the walkthrough?

  Yes, I completed the walkthrough

  No, I did not complete the walkthrough

  I completed part of the walkthrough


Comments and/or feedback